Node / reticulum / RNS-over-HTTP rns://bfb3becae4b7568796ac5276b6bc5741/reticulum/RNS-over-HTTP

Mirrored from rns://06a54b505bb67b25ef3f8097e8001edc/public/RNS-over-HTTP synced 15m ago

A Reticulum interface that tunnels traffic over standard HTTP/S POST requests

󰉖 Files • 󱌣 Work (0) • 󰋚 Commits (25) • 󰘬 Branches (2) • 󰓼 Tags (0) • 󰋑 Thanks (1) •  Stats

RNS-over-HTTP creates a bidirectional transport layer using a simple client-server model:

• Server: Runs on a machine with a public IP, listening for HTTP requests.

• Client: Can be behind a firewall or NAT, only needing outbound internet access.

The client polls the server with HTTP POST requests, sending any outbound data in the request body and receiving inbound data in the response body. This makes the traffic appear as normal web activity.

The interface mimics a persistent connection using a long-polling-like mechanism:

1. The client sends an HTTP POST request to the server, with any pending HDLC-framed packets in the request body.

2. The server receives the request. It deframes inbound packets for Reticulum and immediately sends back any queued outbound packets (also HDLC-framed) in the HTTP response body.

3. The client receives the response, deframes packets, and hands them to Reticulum.

4. After a short, configurable polling interval, the client repeats the process.

This continuous cycle creates a reliable, albeit higher-latency, communication channel.

• Firewall & DPI Evasion: Tunnels any traffic through standard HTTP/S ports (80/443).

• Bidirectional Communication: Full-duplex data transfer.

• Pipe-compatible framing: HDLC FLAG/ESC framing identical to T383838PipeInterface.

• Simple setup: Python, T383838httpx, Hypercorn/aioquic for HTTP/2–3, and Reticulum (T383838rns). Use Poetry in this repo for deps and tests.

• Reliable: Automatic connection retry with exponential backoff.

• Flexible: Supports custom MTU sizes and configurable polling intervals.

• Proxy-Friendly: Works seamlessly behind reverse proxies like Caddy or Nginx.

• Connection reuse: Keep-alive / multiplexed sessions by default, reducing handshake noise visible to DPI.

• HTTP/1.1, HTTP/2, and HTTP/3: Choose the version that matches your path. Default stays HTTP/1.1 for cleartext and reverse-proxy backends.

• Python 3.10 or later

• Poetry (for a reproducible dev environment and tests)

1. Install dependencies with Poetry (from this repository root):

T282828

2. Install the custom interface for Reticulum:

Copy T383838HTTPInterface.py into your Reticulum interfaces directory: T383838~/.reticulum/interfaces/.

T282828

poetry run pytest -m Ta5d6ff"not live"

T8b949e# Full live Reticulum tests (two instances over HTTP + local shared-instance client)

poetry run pytest -m live

Add an interface entry to your Reticulum configuration file (T383838~/.reticulum/config) on both the server and client machines. The config T383838type must match the module basename (T383838HTTPInterface).

The server listens for incoming connections from clients.

T282828

Te6edf3type Tff7b72= Ta5d6ffHTTPInterface

Te6edf3enabled Tff7b72= Ta5d6fftrue

Te6edf3mode Tff7b72= Ta5d6ffserver

Te6edf3listen_host Tff7b72= Ta5d6ff0.0.0.0

Te6edf3listen_port Tff7b72= Ta5d6ff8080

Te6edf3mtu Tff7b72= Ta5d6ff4096

Te6edf3check_user_agent Tff7b72= Ta5d6fftrue

Te6edf3user_agent Tff7b72= Ta5d6ffRNS-HTTP-Tunnel/1.0

The client connects to the server's public URL.

T282828

Te6edf3type Tff7b72= Ta5d6ffHTTPInterface

Te6edf3enabled Tff7b72= Ta5d6fftrue

Te6edf3mode Tff7b72= Ta5d6ffclient

Te6edf3server_url Tff7b72= Ta5d6ffhttp://your-server-ip-or-domain:8080/

Te6edf3poll_interval Tff7b72= Ta5d6ff0.1

Te6edf3mtu Tff7b72= Ta5d6ff4096

Te6edf3user_agent Tff7b72= Ta5d6ffRNS-HTTP-Tunnel/1.0

• T383838mtu: Maximum Transmission Unit in bytes (default: T3838384096).

• T383838name: Interface name for logging and identification.

• T383838user_agent: User-Agent string for HTTP requests and server checks (default: T383838RNS-HTTP-Tunnel/1.0).

• T383838mode: Must be set to T383838server.

• T383838listen_host: Host to bind the HTTP server to (default: T3838380.0.0.0).

• T383838listen_port: Port to listen on (default: T3838388080).

• T383838check_user_agent: Whether to validate User-Agent headers (default: T383838true).

• T383838serve_html_page: Serve an HTML page on GET T383838/ (default: T383838false).

• T383838html_file_path: Path to the HTML file used when T383838serve_html_page is enabled.

• T383838mode: Must be set to T383838client.

• T383838server_url: Full URL of the server to connect to (required for client mode).

• T383838poll_interval: Polling interval in seconds (default: T3838380.1).

• T383838pool_connections / T383838pool_maxsize: Keepalive pool sizing for HTTP/1.1 and HTTP/2 (default: T3838381).

• T383838http_version: T3838381 (default), T3838382, or T3838383.

• HTTP/1.1: cleartext T383838http:// or TLS. Best behind Caddy/nginx that already terminate HTTP/2 or HTTP/3.

• HTTP/2: requires T383838https:// and server T383838tls_certfile / T383838tls_keyfile. Client uses T383838httpx with ALPN T383838h2.

• HTTP/3: requires T383838https:// and the same TLS files. Server enables Hypercorn QUIC bind. Client keeps one aioquic QUIC session across polls.

• T383838tls_verify: client certificate verification (default: T383838true). Set T383838false only for lab/self-signed setups.

• T383838tls_ca_certs: optional CA bundle path for client verification.

• T383838keepalive_timeout: idle keepalive budget in seconds (default: T38383860).

Example HTTP/2 server/client:

T282828

Te6edf3type Tff7b72= Ta5d6ffHTTPInterface

Te6edf3enabled Tff7b72= Ta5d6fftrue

Te6edf3mode Tff7b72= Ta5d6ffserver

Te6edf3http_version Tff7b72= Ta5d6ff2

Te6edf3listen_host Tff7b72= Ta5d6ff0.0.0.0

Te6edf3listen_port Tff7b72= Ta5d6ff443

Te6edf3tls_certfile Tff7b72= Ta5d6ff/path/to/fullchain.pem

Te6edf3tls_keyfile Tff7b72= Ta5d6ff/path/to/privkey.pem

Tff7b72[[HTTP Client Interface]]

Te6edf3type Tff7b72= Ta5d6ffHTTPInterface

Te6edf3enabled Tff7b72= Ta5d6fftrue

Te6edf3mode Tff7b72= Ta5d6ffclient

Te6edf3http_version Tff7b72= Ta5d6ff2

Te6edf3server_url Tff7b72= Ta5d6ffhttps://your-server.example/

Te6edf3tls_verify Tff7b72= Ta5d6fftrue

T282828

Te6edf3exampleTb4b4b4.Te6edf3yourdomainTb4b4b4.Te6edf3com Tb4b4b4{

Te6edf3reverse_proxy T79c0ff127.0T79c0ff.0T79c0ff.1Tb4b4b4:T79c0ff8080

Te6edf3header Tb4b4b4{

# Te6edf3Hide Te6edf3the Te6edf3server Te6edf3software Te6edf3version

Tff7b72-Te6edf3Server

# Te6edf3Prevent Te6edf3MIMETff7b72-Tff7b72type Te6edf3sniffing

Te6edf3XTff7b72-Te6edf3ContentTff7b72-Te6edf3TypeTff7b72-Te6edf3Options Te6edf3nosniff

Tb4b4b4}

Tb4b4b4}

T282828

Te6edf3yourdomainTb4b4b4.Te6edf3com Tb4b4b4{

Te6edf3reverse_proxy T79c0ff127.0T79c0ff.0T79c0ff.1Tb4b4b4:T79c0ff8080

Te6edf3header Tb4b4b4{

# Te6edf3Hide Te6edf3the Te6edf3server Te6edf3software Te6edf3version

Tff7b72-Te6edf3Server

# Te6edf3Prevent Te6edf3MIMETff7b72-Tff7b72type Te6edf3sniffing

Te6edf3XTff7b72-Te6edf3ContentTff7b72-Te6edf3TypeTff7b72-Te6edf3Options Te6edf3nosniff

Tb4b4b4}

Tb4b4b4}

• Use HTTPS: Helps bypass some firewalls and DPI that could potentially see reticulum data.

• User-Agent Check: By default, the server validates the T383838User-Agent header (T383838RNS-HTTP-Tunnel/1.0). This provides basic protection against web crawlers and casual scanning. To mimic a common browser under sophisticated DPI, set a matching T383838user_agent on both sides and keep T383838check_user_agent = true, or set T383838check_user_agent = false on the server.

This project is licensed under the MIT License.